Shareware Grab Bag/Shareware Grab Bag.iso/001/xtalktip.arc/XTALK.TIP

Text File | 1986-03-22 | 17KB | 397 lines

              XTALK.TIP - CROSSTALK SCRIPT Writing Tips
                        Version 1.0  03/22/86

                              JD Morrell
                              Vienna, VA


                              BACKGROUND

The MICROSOFT CROSSTALK script language is very powerful and a lot can
be done  with it, but I do not feel that MICROSTUF has really shown us
the full power of their language.  Because of this I am very surprised
at the absence of magazine or newsletter articles on this topic.  What
you are reading is/was the start of such an article; I just don't have
the time to bring it to completion.

I have  written a  lot of  CROSSTALK scripts and I thought I would set
down some  "hints and  kinks" that  I have  learned as a user over the
years.   Most of  what I  have to  say is *NOT* in the manual, and has
been discovered  the hard  way by  trial and error.  I assume that you
have read  this manual  and  understand  the  basic  CROSSTALK  script
syntax. If  you have not, don't read any further here. Come back after
you have spent an hour or two with the manual.

Some of  the material  only applies  to  the  latest  version  of  the
product, CROSSTALK version 3.6 dated 10/18/85. (Issue the undocumented
CROSSTALK command VErsion to get this information.)

If you would like to comment, ask a specific question, or you catch an
error in  this text,  I would  prefer that  you respond  to me on Gene
Plantz board  in Chicago  (my ID  is ID0346)  (Gene's BBS is telephone
[phone]).  I check in every 7-10 days.  Mail is okay too - 9415
Delancey Dr.,  Vienna, VA 22180.  If you really can't wait, call me at
[phone].   I'll  try and give you a hand with specific scripts,
but please  send me  all the  details and  don't be upset if I put you
off.   I will  add to  and revise  this file  if required and there is
sufficient interest.

If anyone wants to turn this into an article, go ahead.  All I want is
written credit  in the  article for  the ideas and points which I have
dug out the hard way and documented here,  not money.

I have  absolutely no  connection with  MICROSTUF, the  developer  and
owner of  CROSSTALK,   other than  a very satisfied and heavy user for
about 4  years.   MICROSTUF has neither approved (or disapproved) this
text.


                  MOST IMPORTANT: SLOW SCRIPTS DOWN!

I know  "slow-down" advice  almost sounds  un-American but the fact is
that CROSSTALK scripts run *VERY* fast, a fact that can and does cause
a great  deal of  difficulty for the novice.  The CROSSTALK program is
written entirely  in assembler  and in  99% of  the cases  it must  be
"bridled" to work with remote, host systems, especially mainframes.  I
am convinced  that the  omission of delay,  i.e. CROSSTALK out-gunning
the remote  computer, is  the single  most common problem with scripts
written by  beginners.  In general, if your scripts don't work and you
are having  difficulty "working"  with a remote computer, suspect that
this is  your problem  and add delay into your script!  Within reason,
you can not add too much delay or add it too often.  You will not have
a failure  caused by  too much  delay, and  you can easily speed it up
once things are running for you!

You can easily REply too fast (or too early) for a host; it may not be
ready for  your hair-trigger response.  The symptom of this is usually
garbled text echoed back from the host, like "RELL" when you know your
REply command  was "MORRELL|",  or no  response at  all.   Almost as a
matter of  course my scripts include a minimum of 2 tenths of a second
delay (WAit  DElay 2)  prior to  any REply, especially remote prompts,
and they are done like this like this, on one line:

               .
               .
               WAit DElay 2 : REply "MORRELL|"

Note in  particular the spaces and the quoting.  For mainframes, the 2
tenths of a second delay above should be increased to 3 or 4 tenths of
a second  (or more!).   If  you are dealing with a very "hot" BBS, AND
you KNOW  that your  prompt trigger contains the LAST character of the
prompt, you  may use  a delay  of 1  or omit  it  entirely.    (Often,
however, the  last character(s)  of the  prompt (such  as  a  carriage
return or,  more often,  the BELL  character) do  not  appear  on  the
screen, so be careful with zero delays.)

When sending the carriage returns necessary to allow a remote computer
to determine your speed (autobaud), they should generally be separated
by a second or two, like this:

                REply | : WAit DElay 17 : REply |.

If you  just send  REply ||  you will not, in most cases, achieve your
objective.

If and  when you are giving REply commands to your modem (for setup of
a Hayes  2400, for example) your REply commands should be separated by
10 or 20 tenths of a second.

(I assume that all have read the manual and know that CROSSTALK delays
are expressed in tenths of seconds, not seconds, and the maximum delay
is 254  - 25.4  seconds.) (You  may, of  course, have successive delay
commands.)

I can not say it enough. ADD DELAY. ADD DELAY. ADD DELAY . . . and add
it OFTEN!


                          QUOTE REPLY FIELDS

To be safe, quote all reply fields like this:

                 REply "PASS|"     (right)
                 REply PASS|       (wrong)

In some  cases you really don't need the quotes; in others you do.  It
is clear  that if  your REply  contains a space, you need quotes.  But
there are  other cases,  which are too difficult and time consuming to
list, when  they are  required. Be on the safe side, quote all REplys,
except perhaps the straight forward, simple REply |.


                         LINE LENGTH CRITICAL

Never have  a script  line length  greater than 77 visible characters,
even as part of a comment (remark) or a "MEssage" command.  Never! The
result is  an immediate  abort of the script, without any warning. The
manual does  *not* warn you about this.  It is usually the verbose but
very simple  looking remark  line of  77/78 characters  that causes me
grief!


                         STYLE (SUGGESTIONS).

As in  all computer  languages, I  feel that "style" and general rules
for the  use  of  the  language  (grammar)  are  crucially  important.
Unfortunately, we  seem to be a nation of non-conformists and rebel at
even the  idea of  style or  grammar.   And MICROSTUF  does not really
provide us  with any guidance for use of their language.  Much of what
follows then is an attempt to provide style guidelines - a style which
I feel  simplifies the  process of  writing  and  debugging  CROSSTALK
scripts.

Type  the  CROSSTALK  script  commands  with  the  first  two  letters
capitalized, the  remainder in  lower case,  i.e.  REply "xxxx".  This
reminds one that only the first two letters of a CROSSTALK command are
significant, a  fact that  can come  in handy  if you must violate the
line length rule above.


                          LABELS - USE 'EM.

CROSSTALK does  not discriminate  past the 8 character in labels, i.e.
PntrStep1 and  PntrStep2 are the same label, PntStep1 and PntStep2 are
not the  same.   CROSSTALK treats upper and lower case as the same.  I
like and recommend using the mixed-case style shown in the interest of
script clarity and readability.


                       MULTIPLE COMMAND LINES.

The CROSSTALK  manual is not clear that you may have multiple commands
on a line.  You can, but be careful.  The only time you should do this
when it  will clearly  enhance the readability of your scripts, and be
*SURE* to precede *AND* follow the colon separator with a space!

This is  probably the  rule that  I violate  most  often,  usually  to
enhance script  readability.   If I  have trouble,  however, the first
thing I  suspect are  my multiple  command lines.  (The sensitivity to
multiple command  lines appears  to have  become more significant with
version 3.6.)


                AVOID WAIT STRING and WAIT CHARACTER.

I expect some screams of protest from this advice, even MICROSTUF uses
"WAit STring"  in their  examples!   But use of the WAit STring "xxxx"
command can  cause the  script to  hang -  stop running and wait for a
string which  may never  come, possibly running up your phone bill.  I
equate these  two commands  to the  "bad style" of the GOTO command of
BASIC.   Avoid them.   The  better alternative  is to use the style of
Example 1  which may  at first  look complex and un-necessarily formal
but it really isn't.  I think it adds clarity, and eases debuging.  It
also opens  the door to rudimentary logic switches, something that the
present CROSSTALK  really can't do.  (Aha, but the vaporware CROSSTALK
MARK IV can switch - right J.G, K.P.  and L.F.???)

Note that this style is easier to read and follow, and easier to debug
too.   I recommend  it highly.   And  don't think  for a  minute  that
CROSSTALK will  object to  the verboseness  that may result using this
style.   I have  several 30K, 900+ line script files in daily use in a
very critical government applications.  Even here, the biggest problem
has been out-gunning the hosts (more of a pun than you may think!)


            Example 1. Use of WHen in place of WAit STring
                      A CROSSTALK SCRIPT segment
============================================================

LABEL WakeUp
; Purpose: Wakeup remote computer including telling him your speed.
;          then look for FIRST host prompt within time duration
;          indicated. If prompt does not appear, jump to NoGo.
WHen "Name:?" JUmp MyName
WAit DElay 11
REply | : WAit DElay 12 : REPLY |
; (following is the "failure exit")
WAit DElay 51
JUmp NoGo

LABEL MyName
; Purpose: Send FIRST response while looking for SECOND host prompt.
WHen "Password:?" Jump MyPass
WAit DElay 2 : REply "MORRELL|"
WAit DElay 52
JUmp NoGo

LABEL MyPass
; Purpose: Send SECOND response while looking for THIRD host prompt.
WHen "Whatever" Jump ImOn
WAit DElay 2 : REply "PASS|"
WAit DElay 53
JUmp NoGo

LABEL ImOn
; Purpose: Set for operator interaction with host.
;          by WHen shutoff and aborting the SCRIPT (NOT THE CALL!)
WHen -
CLear
message



              You are logged onto the XYZ BBS thanks to
              CROSSTALK and your fine SCRIPT writing skills.
.
ABort

LABEL NoGo
; Purpose: Allow time for operator intervention.
;          Closes down CROSSTALK if not interrupted by operator
ESCAPE.
WHen -
CLear
ALarm 3 NOW
MEssage



            Sorry, your autologon was not successful.
            Will hang up the telephone in 10 seconds
            and quit CROSSTALK.
.
WAit DElay 101
BYe
QUit

==================== ( End of Example 1 ) ============================


Note that  if any  string is  not received  in the specified period of
time the  script "falls through" to "NoGo", which, unless the operator
terminates the  script within  10 seconds (by hitting the ESC key), he
will be disconnected from the telephone line and returned to DOS.

Several elements  of CROSSTALK script style are shown here.  All of my
scripts use  the basic  modular, structure  shown above;  they can  be
viewed as being built around WHen commands.  Each "module" has a label
reflecting what  it is  to do,  followed by  a "Purpose"  comment line
expanding on  what task is to be performed.  I use a delay of "51, 52,
53" to  really mean  5 seconds (rather than just 50) as clue to let me
trace where I am in my script as it runs.  (A debug aid!)


                  WHEN - THE MOST POWERFUL COMMAND.

Note that the WHen command (and many other script commands) can be set
at the normal CROSSTALK command line. Typing the following:

                    WHen "MORE-Y/N" REply |

tells CROSSTALK  to send  a carriage  return when  it sees "MORE-Y/N".
This can  be a  handy little  feature to  remember when  your on  line
giving the same command over and over.

Be aware  that the  WHen command  can get you in LOT of trouble unless
you turn  it off  explicitly with a  WHen -  command.  Once invoked it
stays active even when the script is terminated (ABort'ed). This fact,
by the way, can be a feature.  It can be used to restart a SCRIPT file
suspended with  a WAit  MAnual command,  or to  start an  entirely new
SCRIPT file!


                            RWind - NEEDED

Use a  RWind command  before jumping  to a  label  ABOVE  the  present
position in the script file. For example:

         use    WHen "MORE-Y/N"   RWind : JUmp UpAbove
         but    WHen "MORE-Y/N" JUmp DnBelow
                can be used if the LABEL is below this WHen.

Be sure, if you use the WAit MAnual command and return, to use a RWind
if you  JUmp to a LABEL above where you left off.  Not doing this cost
me an afternoon of frustration!


                     ELIMINATE OPERATOR PROMPTS.

If CROSSTALK  feels that  you are about to make a regrettable error it
asks if you really want to do what you commanded.  For example, if the
file GENE.MSG  exists on  the drive,  the script file command "CApture
GENE.MSG" will  cause CROSSTALK  to ask  the operator  if he  wants to
erase the  present file  first or  append to  it.  The command CApture
GENE.MSG /A  causes eliminates  this warning appends to the file.  (/E
would have erased the file.) This feature is part of the documentation
but seems to escape the attention of many.

One one  significant place where it is *NOT* part of the documentation
is an  option with  the very  useful RUn command.  I for one feel that
MICROSTUF crippled  this command by requiring a user to "Press any key
to return  to CROSSTALK".   But  they allow  you to  eliminate this by
using the syntax:

                         RUn / MYPROG

CROSSTALK will  exit and  run the  program and  come right back to the
script file  at the  point that  called it.   VERY  HANDY. I  use this
feature for  a multiple  of uses  including calling a PROKEY file into
the system,  issuing a form feed to the on line printer when a certain
key sequence  is sent  by the  remote  computer,  switching  printers,
logging time  and many  other housekeeping tasks. Let your imagination
run! You can do a whole lot with this one!

A word  of caution is in order IF you call a BASIC(A) program from the
RUn command.  BASIC resets the communications port resulting in a case
where data  incomming data  from the  remote host  is lost.   The work
around, as  reported to  me by  MICROSTUF, is  to simply  issue a POrt
command immediately  upon return  to the script, like this, if you are
using POrt 1:

                    RUn / BASICA MYPROG
                    POrt 1

MICROSTUF  confirms   that  omission   of  the  /  modifier  from  the
documentation was  unintentional, i.e  it  is  not  an  "undocumented,
unsupported" feature.  (Funny, but the RUn / command was documented in
the the  3.6 10/08/85  "on-line help"  section but NOT in the 10/18/85
version.)


                           LFAUTO COMMAND.

Note that  the LFauto  command does  *NOT* operate  unless INfilter is
*ALSO* turned  on.  I think this is a bug. I have told MICROSTUF about
it but has existed in all CROSSTALK versions from 3.2 on.


                           3101 EMULATION.

Note that  there is  some problem  in version  3.6 10/18/85  with 3101
emulation with  text overwriting  the CROSSTALK  command  line.  These
errors did not occur in prior versions.


                            SCREEN TRICKS.

Note that  you can  use the  "SCreen" commands  to change the color of
your messages  on the  screen and  command line.   This  can  be  very
effective in  some situations,  and as  an aid for inexperienced user.
See the  manual page  52 for details.  For example, you may set colors
prior to  using the  ASk command and tell the user "touch the keyboard
only when the command line is green, and never when it is red."

CROSSTALK unfortunately  does not  provide any  means to  turn off the
screen, i.e.   to  have host  text NOT be displayed.  Users with color
systems, however,  can send  unwanted host text to the garbage heap by
using a SCreen command with the following form:

               SCreen N bB

This syntax  sets the  "normal" screen  to print  a foreground of dark
blue on  a background of bright blue.  All one sees is a moving cursor
- no mainframe nonsense messages that might confuse a user. Just don't
forget to re-set it back, something like this:

               SCreen N wb     (white on a blue background)


                             KERMIT NOTES

I  have  found  that  KERMIT  commands  seem  to  *require*  that  the
communications parameters  be set  to DAta 8. (DAta 7 does not seem to
work although I think it should.)

                                                 XTALK.TIP 03/22/86